Light Path ExpressionΒΆ

Introduction

A light path expression is a regular expression representing the different interaction of a photon with the scene between the camera and a light. Guerilla comes with many presets, but you can create your own expression.

For example, CDL matches the direct lighting on a diffuse surface: a path of three events, each represented by a capital letter: Camera, Diffuse and a Light. Note that the light path is expressed going from the camera towards the light, such that a CDL path is to be read as camera then diffuse then light.

Guerilla Preset LPEs

Guerilla offers a set of predefined LPEs to ease the setup of classic AOVs, such as Diffuse, Reflection, and so on. The LPE syntax is explained below this subsection.

AOV Expression Meaning
All C.*# from the camera to the light with anything inbetween. Note that straight from the camera to the light is accepted, and represents the illumination on light on primary rays.
Diffuse C[<RD><VD>]# from camera to either a reflective diffuse or volumetric diffuse to a light. Note that this expresion does not include the translucence, as it is categorized as <TD> for Transmitted Diffuse.
Specular C[<RS><RG>]# from camera to either a reflective singular or glossy to a light.
Volume C<VD># from camera to a volumetric diffuse to a light.
Indirect Diffuse C[<RD><VD>].+# from camera to either a reflective diffuse or volumetric diffuse to at least another interaction and then to a light. Note that this is close to the Diffuse expression, with the addition of .+ token to enforce the indirect illumination.
Reflection C[<RS><RG>].+# from camera to either a reflective singular or glossy to at least another interaction and then to a light. Note that this is close to the Specular expression, with the addition of .+ token to enforce the indirect illumination.
Incandescence C[<LS><LV>] from camera to a surface light or volumetric light. Note that this automatically excludes classic lights since they are tagged as <L.category>.
Lights C# from camera to a light. Note that, depending on the light category, this may or may not capture the incandescence as well. Capturing lights without the incandescence is written C<L[^VS]> because [^VS] stands for anything but V or S.
Direct SSS C<OD><OD># from camera to 2 object diffuse events to a light. Note that the subsurface scattering is implemented as 2 consecutive object diffuse events, one for entry point on the surface and the other for the exit point on the surface.
Indirect SSS C<OD><OD>.+# from camera to 2 object diffuse events to at least another event and then to a light.
SSS C<OD><OD>.*# from camera to 2 object diffuse events to at any another event and then to a light. This AOV is a legacy from previous versions of Guerilla, because Guerilla would then not differentiate direct sss from indirect sss.
Refraction C[<TS><TG>].*# from camera to either a transmitted singular or glossy to any other event and to a light. Note that this will capture the direct and indirect illumination through refraction.
[Technical] Primary C~ Technical values, such as Pcam, Ncam, in primary. Note that the ~ character is expanded to <I.shadercolor> where shadercolor is the Shader Color name set in the AOV.
[Technical] Indirect Singular CS+~ Technical values, such as Pcam, Ncam, after any number of singular bounce. Note that values may get accumulated along the path.

Other examples are

  • C<TD># for direct translucence
  • C<TD>.+# for indirect translucence
  • C<VD># for direct volumetric diffuse (also called volumetric single scattering)
  • C<VD>.+# for indirect volumetric diffuse
  • C<VD><VD># for second order volumetric scattering

Regular Expression Syntax

The regular expression syntax can be used to match an event sequence. Many events are composed together using the following combiners:

Symbol Meaning Example
. Any Event C.L: Direct lighting on any surface
X* 0 or more X CG*DL: 0 or more Glossy followed by a Diffuse
X+ 1 or more X CD+L: 1 or more Diffuse
X|Y X ou Y C(DD|G)L: Two Diffuse or one Glossy
(XYZ) Grouping Usually used with the | operator
X{5,} 5 or more X
X{5, 10} between 5 and 10 X
[XYZ] X or Y or Z Only works for event, not groups of event
[^XYZ] none of X, Y, Z Only works for event, not groups of event

Event Rules

An event is characterized by:

  • Its type
  • Its scattering
  • Its label

Type, Scattering and Labels are combined with the extended event syntax: <TSL>, using . as wildcard. For example, <RS.> is an event with type Reflexion, scattering Singular and any label.

When it is not ambiguous, you can replace the extended event syntax by a single component. <L..> is equivalent to L.

Type description

EndPoints (Lights or Technicals):

  • C: Camera, all expressions will start by that
  • L: Light, all expressions but technical passes end with it
  • I: Information (Technical passes)

MiddlePoint (Surface or Volume):

  • R: Reflexion, the light bounce on a solid object
  • T: Tranmission, the light go through a solid object
  • V: Volume scattering
  • O: in-Object scattering (SSS)

Scattering description

EndPoints (Lights or Technicals):

  • S: Surface light
  • V: Volume light
  • 'aLabel': A technical passe named aLabel.

MiddlePoints (Surface or Volume):

  • S: Singular, perfect scattering, such as mirror or glass
  • D: Diffuse, rough scattering
  • G: Glossy, focused scattering

Labels

An event can also be represented by a label, such as 'Label'. Labels are used for light groups (using the Light Category on the light) and object names (using the LPE Tag attribute on the objects.) Labels can also appear in the scattering description of an technical pass I.

LPE Tags offer a powerful way of filtering specific objects of the rendering. For example, C.*'mytag'.*# selects all light paths that would interact with objects that have mytag in LPE Tag.

C.*#: the default beauty.

C.*'mytag'.*#: all illumination paths that encounter the rightmost object.

C[^'mytag'].*'mytag'.*#: all illumination paths that encounter the rightmost object, excluding primary hits.

Guerilla specific tokens

To help with setting light categories selection and technical AOVs, we've added 2 special tokens: the # and ~ characters.

Filtering light categories

The # character is replaced for each AOV by <L.category> where category is the light category selected in the AOV. So, instead of defining the BeautyRim AOV with the C.*<L.'RimLight'> expression, you can write C.*# instead and select the RimLight category in the AOV, which will automatically substitute # with <L.'RimLight'>.

Filtering technical AOVs

The ~ character is replaced for each AOV by <I.shadercolor> where shadercolor is the shader color selected in the AOV.

Tips

  • A technical output, such as Albedo, can be matched with an expressing ending by <I'Albedo'>.
  • Avoid matching only on I without a label, you'll get the sum of all technical output.
  • Similarly, avoid path expressions with unspecified endpoint. For example, C.* will match all light path, including technical ones, while C.*L only captures light paths.
  • ...~ is equivalent to ...<I'ShaderColor'.>, using the Shader Color setting of your AOV.
  • ...# is equivalent to ...<L.['lightCategoryA''lightCategoryB']> with as many cases as selected light categories in your AOV settings.

Examples

Capture only the Diffuse on light category RimLight

CD'RimLight'

Capture only the direct lighting on object Alice

C'Alice'L

Capture Albedo after two Singular Transmissions (i.e. through a glass)

C<TS>{2}<I.'Albedo'>

Capture only the Diffuse direct lighting Reflection on object Alice

C<RD'Alice'>L

Capture any Transmission on Alice

C<T.'Alice'>L

Capture the Albedo of object Alice after a Singular Reflection on Bob

C<RS'Bob'><I'Albedo''Alice'>

Capture the direct lighting on Diffuse, Glossy and Singular Reflexions

C<R[SDG]>L

Advanced light path expressions

If the default presets are not enough, you can customize them with Light Path Expression. The page on Light Path Expression syntax details the syntax, but the following overview may be enough for most needs.

Using a mix of Accept Path and Ignore Path, you can filter in or out light paths based on their characteristics such as depth, type of interaction (diffuse, glossy, singular), reflection or refraction, name of object or lights. Technical passes are included in the framework, so you can get the normal of an object see through the reflection on another object.

All the following examples uses Caustics as Ignore Path.

This section use formatting to help readability. A label can appear in an event <L.'label'> which is part of a bigger light expression C'Alice'L.

C.+L: The Scene is a cornel box composed of two spheres. Left red wall is tagged as RedWall and right blue wall is tagged as BlueWall. Top light is a white square light, tagged as White. Left square light is greenish and tagged as Green.

CDL: Diffuse direct lighting.

CD+L: At least one Diffuse. It includes Diffuse direct and indirect lighting.

CDD+L: At least two Diffuses. This is Diffuse indirect. It may had been written as CD{2,}L.

C<RS>L: Singular Reflection.

C<RS>DL: A Singular Reflection followed by a Diffuse surface.

C<RS>{2}DL: Exactly two Singular Transmissions followed by a Diffuse surface.

CD<L.'Green'>: Direct lighting from the Green light.

CD<L.'White'>: Direct lighting from the White light.

CDD+<L.'Green'>: Indirect lighting from the Green light.

C<RS><.D'RedWall'>L: Singular Reflection followed by the RedWall surface. It may had been written has C<RS>'RedWall'L because the RedWall is only composed of a Diffuse component.

C<RS><I'Albedo'>: Albedo seen through one Singular Reflection.

C<RS><I'Albedo''RedWall'>: Albedo of the RedWall seen through one Singular Reflection.

C((<TS>{2}'BlueWall')|(<RS>'RedWall'))L: Two Singular Transmissions (through the glass) followed by lighting on the BlueWall, OR a Singular Reflection followed by the RedWall.